The Extended Menu Resource
NEW WITH THE APPEARANCE MANAGER
After reading in a'MENU'resource,GetMenulooks for an extended menu resource of type'xmnu'with the same resource ID. The extended menu resource allows you to create menus with modifier key keyboard glyphs and icons attached to menu items and Appearance-compliant menu backgrounds. The information is set for specified menu items (it is not necessary to create an extended menu entry for each item). At this point, the information can be purged or released. Figure 5-3 shows the format of a compiled'xmnu'resource.
Figure 5-3 Structure of a compiled extended menu('xmnu')resource
A compiled version of an
'xmnu'resource contains the following elements:
Figure 5-4 shows the format of an extended menu item entry.
- Version number. An integer specifying the version of the resource.
- Number of entries. An integer that specifies the number of entries in the resource. Each entry is an extended menu item structure.
- Extended menu item entries. A series of extended menu item structures, each of which consists of a type, command ID, modifier keys, text encoding, reference constants, menu ID of submenu, font ID, and keyboard glyph.
Figure 5-4 Structure of an extended menu item entry
Each entry in a
'xmnu'resource corresponds to a menu item and contains the following:
- Type. An integer that specifies whether there is menu item information for the item in the
'MENU'entry. If this is 0, there is no information for the item in the corresponding'MENU'entry, and the rest of the record is skipped. If this is 1, there is information for the item in the corresponding'MENU'entry, and the rest of the record is read.- Command ID. A unique value which you set to identify the menu item (instead of referring to it using the menu ID and item number). You can also call
SetMenuItemCommandIDto set the command ID of a menu item. After a successful call toMenuSelect,MenuEvent, orMenuKey, you can callGetMenuItemCommandIDto determine its current value.- Modifier keys. A mask that determines which modifier keys are used in a keyboard equivalent to select a menu item; see "Modifier Key Mask Constants".
- Reserved. Set to 0.
- Reserved. Set to 0.
- Text encoding. A long integer which indicates the text encoding which your item text will use. Use
currScriptfor the default text encoding. To change this value, callSetMenuItemTextEncoding. You can callGetMenuItemTextEncodingto determine its current value. This should be used instead of setting a menu item's modifier key to 0x1C and its icon ID to the script code.
- If you wish the text of the menu item to use the system script, this value should be -1. This should be used as the default.
- If you wish the text of the menu item to use the current script, this value should be -2.
- Reference constant. Any value that an application wishes to store. To change this value, call
SetMenuItemRefCon. You can callGetMenuItemRefConto determine its current value.- Reference constant. Any additional value that an application wishes to store. To change this value, call
SetMenuItemRefCon2.You can callGetMenuItemRefCon2to determine its current value.- Menu ID of submenu. A value between 1 and 235, identifying the application submenu.
- Font ID. An integer representing the ID of the font family. If this value is 0, then the system font ID is used.
- Keyboard glyph. A symbol representing a menu item's modifier key. In Appearance 1.0, if the value in this field is zero, the keyboard glyph uses the system font. In Appearance 1.0.1, if the value in this field is zero, the keyboard glyph uses the keyboard font; see Table 5-1. Use of the keyboard font (rather than the system font) provides a consistent user interface across applications, since a modifier key's symbol will not change regardless of what system font is running. If the value in this field is nonzero, you can override the character code to be displayed with a substitute glyph.
- Reserved. Set to 0.
Table 5-1 Keyboard font character codes
Character code Description 0x00 Null (always glyph 1) 0x01 Unassigned (reserved for 2 bytes) 0x02 Tab to the right key (for left-to-right script systems) 0x03 Tab to the left key (for right-to-left script systems) 0x04 Enter key 0x05 Shift key 0x06 Control key 0x07 Option key 0x08 Null (always glyph 1) 0x09 Space (always glyph 3) key 0x0A Delete to the right key (for right-to-left script systems) 0x0B Return key (for left-to-right script systems) 0x0C Return key (for right-to-left script systems) 0x0D Nonmarking return key 0x0E Unassigned 0x0F Pencil key 0x10 Downward dashed arrow key 0x11 Command key 0x12 Checkmark key 0x13 Diamond key 0x14 Apple logo key (filled) 0x15 Unassigned (paragraph in Korean) 0x16 Unassigned 0x17 Delete to the left key (for left-to-right script systems) 0x18 Leftward dashed arrow key 0x19 Upward dashed arrow key 0x1A Rightward dashed arrow key 0x1B Escape key 0x1C Clear key 0x1D Unassigned (left double quotes in Japanese) 0x1E Unassigned (right double quotes in Japanese) 0x1F Unassigned (trademark in Japanese) 0x61 Blank key 0x62 Page up key 0x63 Caps lock key 0x64 Left arrow key 0x65 Right arrow key 0x66 Northwest arrow key 0x67 Help key 0x68 Up arrow key 0x69 Southeast arrow key 0x6A Down arrow key 0x6B Page down key 0x6C Apple logo key (outline) 0x6D Contextual menu key 0x6E Power key 0x6F F1 key 0x70 F2 key 0x71 F3 key 0x72 F4 key 0x73 F5 key 0x74 F6 key 0x75 F7 key 0x76 F8 key 0x77 F9 key 0x78 F10 key 0x79 F11 key 0x7A F12 key 0x87 F13 key 0x88 F14 key 0x89 F15 key 0x8A Control key (ISO standard)
